
rdump.txt

File Analysis and RATF Analysis using RD (Random Dump)
======================================================

Synopsis:
========

RD Random Dump Hex Viewer
--

RD(random dump)(C) Copyright Bill Buckels 2013. All Rats Reserved.
Usage: rd options file1 [options] [file2] ... [> myfile.txt]
This program performs a dump in hex and ascii of the specified
file(s) to the standard output. Default is to the screen but can
also be redirected to a file, a printer, or through a filter program.
Options: r p w l o h t - options with values cannot be combined.
+  switch on - options without values can be combined i.e. +rpt
+r switch - view file as random access text file
+p switch - view file a page at a time - Q or ESC to exit
+w(value  - decimal) - display width 1-16 (default 16)
+l(value  - decimal) - record length 1-256 (off by default)
+o(value  - decimal) - view file beginning at offset (default is 0)
+h(value  - hexadecimal) - same as above
+t switch - view file as 7 bit values (strip hi-bits - all files)
-  switch off - options can be combined or separate i.e. -rp or -r -p
Over-rides: +s(slot 4 5 6 7) +d(drive 1 2) +v(volume 1-255)

RD is a command line program for the Aztec C65 DOS 3.3 "Unix-like"
Shell written in Aztec C65 (CII Version).

RD has more features than a typical hex viewer including user defined screen
width and record length and provides a view of all DOS 3.3 file types.

Example RD Output: Default Width - Record Length = 30 (+L30)
------------------------------------------------------------

Command Line: RD +RT +L30 RATF > myfile.txt

00000 46 49 52 53 54 0D 00 00 00 00 53 45 43 4F 4E 44  FIRST.....SECOND
00010 0D 00 00 00 54 48 49 52 44 0D 00 00 00 00        ....THIRD.....  

0001E 46 49 52 53 54 0D 00 00 00 00 53 45 43 4F 4E 44  FIRST.....SECOND
0002E 0D 00 00 00 54 48 49 52 44 0D 00 00 00 00        ....THIRD.....  

0003C 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
0004C 00 00 00 00 00 00 00 00 00 00 00 00 00 00        ..............  

0005A 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
0006A 00 00 00 00 00 00 00 00 00 00 00 00 00 00        ..............  

Sample RD Output: Width = 10 (+W10)
-----------------------------------

Command Line: RD +RT +L30 +W10 RATF > myfile.txt

00000 46 49 52 53 54 0D 00 00 00 00                    FIRST.....
0000A 53 45 43 4F 4E 44 0D 00 00 00                    SECOND....
00014 54 48 49 52 44 0D 00 00 00 00                    THIRD.....

0001E 46 49 52 53 54 0D 00 00 00 00                    FIRST.....
00028 53 45 43 4F 4E 44 0D 00 00 00                    SECOND....
00032 54 48 49 52 44 0D 00 00 00 00                    THIRD.....

See below for a more detailed description:

Syntax
======

Options consist of a logical operator (a '+' or a '-') followed by a single
letter. They are not case sensitive.

Turning On Options
------------------

To turn on an option, precede the option with a '+' (plus sign) followed by
the single letter of the option.

Options with values must be specified separately. Options without values
(switch options) can be combined i.e. +rpt

Some options require a numeric value (in decimal) which must directly
follow its letter.

The +h (hex offset) is the only option that requires a hexadecimal value.
The +o (offset) option is the decimal equivalent of the -h option. Both do
the same thing.

Turning Off Options
-------------------

The only time you will need to turn-off an option is between files when
listing multiple files.

To turn off an option, precede the option with a '-' (minus sign) followed
by the single letter of the option. This will restore that option's default
settings for the files that follow.

RD has no option to turn-off all options.

When turning off options a numeric argument is never required, only the
single letter of the option.

Order of Operations
-------------------

Options must precede the file(s) they apply to.

An option remains in effect until it is turned-off, or gets a new value.

Input
=====

Directly Supported File Types
-----------------------------

RD directly supports all DOS 3.3 filetypes except for Random Access Text
Files (RATF's).

By default RD (and other Aztec C65 programs) assume that all text files are
sequential as they are on modern systems.

All other DOS 3.3 file types are viewed with "heads" and "tails" intact (by
the complete sectors allocated to the file).

DOS 3.3 programmers have been free to store whatever they wanted in any file
type. If the length information fields in files like binary files have been
"adjusted" and used for some other reason they cannot be depended on. The
native version of Aztec C65 CII does exactly that with its library files,
so you can't always depend on the length field, even in a BIN file. It may
have been used for something else.

RATF's Indirectly Supported - Random Text Option +r
---------------------------------------------------

RD indirectly supports RATF's with the +r option. To view a RATF in RD, use
the +r option. When the +r option is in effect all text files both
sequential and RATF will be displayed with "tails" intact. If you view a
RATF without using the +r option, the view will truncate immediately after
the first NUL byte is reached (probably on the first field).

When the +r option is in effect, RD changes the DOS 3.3 filetype being read
to type S before reading the file, and changes it back to its original type
afterwards. However, if the +r option is in effect, and you abort RD using
ctrl-C you should use the chtype utility (or some other means) to change the
aborted type S file back to its original type.

Some notes about RATF's and DOS 3.3 Type S Files
------------------------------------------------

In order to protect BASIC programmers from themselves, DOS 3.3 BASIC opens
text files only and no other DOS 3.3 file types. A DOS 3.3 BASIC program
will generate a FILE TYPE MISMATCH error when it tries to open a type S
file, or any DOS 3.3 file type other than a text file, so it is only
necessary to keep RATF's as text files to share with BASIC and other
applications that expect a RATF to be a text file.

But there is no other reason that a RATF cannot be a type S file.

And if you want to protect your RATF from DOS 3.3 BASIC programmers, change
your RATF to a type S and leave it that way. You can use the chtype utility
that comes with the RAT (or some other means) to change it to a type S file.

To sum up; you can avoid the need to use the +r option to repetitively view
a RATF if you use the chtype utility (or some other means) to change it to
type S file before viewing in RD.

Output
======

Unless the paging option is on, the program continues until the end of the
file and then dumps the next file if any.

Output can redirected to a file:

i.e. rd infile > outfile

Paging Option (Pause Option) +p
-------------------------------

If the paging option is on, the specified file(s) can be displayed a page at
a time (or optionally a record at a time) with a pause in between. RD can be
exited at each pause by pressing ESC or Q. Pressing another key advances to
the next pause.

The +l (record length) option (noted further) modifies the behaviour of the
+p (paging) option when the paging option is in effect. The paging option
normally fills the screen with 23 lines before waiting for a keypress. The
record length option stops between records and waits for a keypress.

Abort Option ctrl+C and Suspend Toggle ctrl+S
---------------------------------------------

But even if the paging option is off, the display can be temporarily paused
and resumed (toggled) by using the ctrl+S key combination, and RD can be
aborted at any time by pressing ctrl+C (BREAK). However, do not abort RD if
the +r option is in effect. See the input section above for more
information.

Display Width Option +w(display width)
--------------------------------------

RD is an extended version of the od program which was originally provided
with the C65 CII DOS 3.3 compiler. The od program offered a fixed display of
8 bytes at a time. RD defaults to a 16 byte display width like other 80
column hex viewers.

RD's display width can be set to any width within the range of 1 to 16 by
using the +w option. This makes it easier to view a file containing fixed
length records on record boundaries.

For a record aligned view of longer records, if you know the length of a
record just divide the length equally divisible by the highest value of the
numbers 1-16 and that will give you your optimum viewing width.

For a record aligned view of shorter records, use a similar approach, but
first decide on a multiple that will fit onto the screen and if using the
paging option, that will break on record boundaries of 23 lines

The offset options -o or -h discussed below can be used to jump past a
header of a different size than the records.

This view is not just for database files. For example, uncompressed binary
screen files with known header sizes and known scanline lengths can be
aligned using a flexible width combined with a starting offset.

One wonders why all hex viewers do not have this option. Viewing hex in 8 or
16 byte paragraphs is not always the optimum display width for analysis.

Record Length Option +l(record length)
--------------------------------------

The +l (record length) option aligns the beginning of each record to the
left edge of the display. When the end of each record is reached a blank
line will be displayed. The following record will start from the left edge
of the display again until the end of file is reached.

As noted previously, the +l (record length) option modifies the behaviour of
the +p (paging) option when the paging option is in effect, and stops
between records and waits for a keypress.

If viewing a Random Access Text File (RATF), the +l option used in
conjunction with the offset option (see below), each field position can be
determined. A header record in a flat file followed by fixed length data
records can also be jumped past using this same technique.

Offset Option +o(offset in decimal) and +h(offset in hex)
---------------------------------------------------------

+onnn

If the optional decimal (base 10) argument "+onnn" is supplied. "nnn" is
used as an offset into the file where the dumping is to start. Alternately:

+hxxx

If the optional hexadecimal (base 16) argument "+hxxx" is supplied. "xxx" is
used as an offset into the file where the dumping is to start.

For multiple files, each file will be dumped starting from the last offset
argument encountered. Thus, an offset of "+o0" or "+h0" will cause the files
which follow to be dumped from their beginning, and so will turning off the
offset option using "-h" or "-o".

For example the following offsets are all equivalent:

rd +h16b oldtest newtest +o0 junk
rd +h16b oldtest newtest +h0 junk
rd +h16b oldtest newtest -o junk
rd +h16b oldtest newtest -h junk
rd +o363 oldtest newtest +o0 junk
rd +o363 oldtest newtest +h0 junk
rd +o363 oldtest newtest -o junk
rd +o363 oldtest newtest -h junk

Text (and Hex) Display Format - Apple II or 7 Bit Plain Text - Option +t
========================================================================

The +t option strips hi-bits from both the hex and text views of all files,
primarily to view DOS 3.3 text files as plain 7 bit ascii, but also to view
the unmasked 7 bit ascii values of other files that may contain DOS 3.3 text
(like type S files). S files (and any other files) will still display 7 bit
text properly when +t is on, and DOS 3.3 text will also display properly as
7 bit text.

The +t option can also be useful when viewing sequential text files in
determining the hex value of control characters like carriage returns, line
feeds, page feeds, that do not show-up in the right side of the display
because they are unprintable.

The +t option is "technically" incorrect for viewing the values of "known"
binary data (BIN files, BAS Files, INT Files, REL Files) unless you are
looking for DOS 3.3 text in the data, as in the case of type S files.

Note: The hex view in the CiderPress program's file viewer always displays
clear text on the right side of a text file, but always displays the actual
hex value of the bytes in a text file in the hex view. This is the default
behaviour of RD as well (thanks to Andy McFadden for providing the rationale
for this default).

When the -t option is used in RD, the hex view (the left side of the
display) gives hex values as 7 bit values (hi bits stripped).

Last Word
---------

Good luck using RD (Random Dump) and the other programs it comes with.

Bill Buckels
Aug 2013